/*
 * File Name: StatefulView.java
 *------------------------------------------------------------------------------
 * Copyright 2012 NCR Corporation
 *------------------------------------------------------------------------------
 * All revision information is updated automatically from source code control
 * change records - please do not manually edit.
 *------------------------------------------------------------------------------
 *
 * $LastChangedRevision:: 1569                                     $
 * $LastChangedBy:: rb250096                                       $
 * $LastChangedDate:: 2012-02-21 00:50:19 -0500 (Tue, 21 Feb 2012) $
 */

package com.ncr.nep.dashboardcore.mvp.client;

/**
 * A MVP View that provides the concept of display state (like view states in
 * other UI frameworks such as WPF or Flex).  
 * <p>
 *     With display state, the View can be queried to determine its current 
 *     viewable state (for instance, if the view is in a waiting state while a 
 *     asynchronous operation is in progress).  In addition, a pattern is 
 *     provided for aggregating multiple view manipulation operations together 
 *     and invoking them by setting the current display state of the View.
 * </p>
 * <p>
 *     In regards to GWT, display states are represented as an {@link Enum}.
 *     Views and presenters can then create enums that define the different
 *     states of the view, and associate logic to be applied when each is set.
 * </p>
 * 
 * @author rb250096
 * @version $Revision: 1569 $
 */
public interface StatefulView<T extends Enum<?>> extends View {

    //--------------------------------------------------------------------------
    //
    //  Properties
    //
    //--------------------------------------------------------------------------

    /**
     * Gets the display state of the view as an enumeration value.
     *
     * @return The enumeration value representing the current state of the view.
     */
    T getViewState();

    /**
     * Sets the display state of the view.
     * 
     * @param viewState Enumeration value representing the new display state
     *                     to apply.
     */
    void setViewState(T viewState);

    //--------------------------------------------------------------------------
    //
    //  Methods
    //
    //--------------------------------------------------------------------------

    /**
     * Applies the provided display state to the view.
     *
     * @param viewState Enumeration value representing the new display state
     *                     to apply.
     */
    void applyViewState(T viewState);
}
